remark-gfm

What is remark-gfm?

The remark-gfm npm package is a plugin for remark, a markdown processor powered by plugins part of the unified collective. It adds support for GitHub Flavored Markdown (GFM) to remark, enabling additional syntax features that are commonly used on GitHub.

What are remark-gfm's main functionalities?

Table

Enables support for GFM tables, allowing you to create tables in markdown.

const remark = require('remark');
const gfm = require('remark-gfm');

remark().use(gfm).processSync('| Syntax | Description |
| ----------- | ----------- |
| Header | Title |
| Paragraph | Text |').toString();

Strikethrough

Adds the ability to use strikethrough text using double tildes (~~).

const remark = require('remark');
const gfm = require('remark-gfm');

remark().use(gfm).processSync('~~Strikethrough~~').toString();

Tasklist

Supports task lists with checkboxes, a common feature in GitHub issue and pull request comments.

const remark = require('remark');
const gfm = require('remark-gfm');

remark().use(gfm).processSync('- [ ] todo item
- [x] done item').toString();

Autolink Literals

Automatically converts URLs and email addresses into links.

const remark = require('remark');
const gfm = require('remark-gfm');

remark().use(gfm).processSync('Autolink: https://example.com').toString();

Other packages similar to remark-gfm

markdown-it

markdown-it is a Markdown parser with GFM support and a similar plugin ecosystem. It is often used for its performance and extensibility but is not part of the unified collective.

showdown

showdown is another Markdown to HTML converter that supports GFM. It is known for its client-side capabilities and can be used in the browser, which differs from remark-gfm that is typically used in Node.js environments.

marked

marked is a fast markdown parser and compiler. It supports GFM and is designed to be lightweight and simple to use. It is a standalone package, unlike remark-gfm which is a plugin for remark.

README

remark-gfm

remark plugin to support GitHub Flavored Markdown.

Important!

This plugin is made for the new parser in remark (micromark, see remarkjs/remark#536). While you’re still on remark 12, use the gfm option for remark. Use this plugin for remark 13+.

Install

npm:

npm install remark-gfm

Use

Say we have the following file, example.md:

# GFM

## Autolink literals

www.example.com, https://example.com, and [e-mail].

## Strikethrough

~one~ or ~~two~~ tildes.

## Table

| a | b  |  c |  d  |
| - | :- | -: | :-: |

## Tasklist

* [ ] to do
* [x] done

And our script, example.js, looks as follows:

var vfile = require('to-vfile')
var report = require('vfile-reporter')
var unified = require('unified')
var parse = require('remark-parse')
var gfm = require('remark-gfm')
var remark2rehype = require('remark-rehype')
var stringify = require('rehype-stringify')

unified()
  .use(parse)
  .use(gfm)
  .use(remark2rehype)
  .use(stringify)
  .process(vfile.readSync('example.md'), function (err, file) {
    console.error(report(err || file))
    console.log(String(file))
  })

Now, running node example yields:

example.md: no issues found
<h1>GFM</h1>
<h2>Autolink literals</h2>
<p><a href="http://www.example.com">www.example.com</a>, <a href="https://example.com">https://example.com</a>, and <a href="mailto:[e-mail]">[e-mail]</a>.</p>
<h2>Strikethrough</h2>
<p><del>one</del> or <del>two</del> tildes.</p>
<h2>Table</h2>
<table>
<thead>
<tr>
<th>a</th>
<th align="left">b</th>
<th align="right">c</th>
<th align="center">d</th>
</tr>
</thead>
</table>
<h2>Tasklist</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled> to do</li>
<li class="task-list-item"><input type="checkbox" checked disabled> done</li>
</ul>

API

remark().use(gfm[, options])

Configures remark so that it can parse and serialize GFM (autolink literals, strikethrough, tables, tasklists).

options

options.singleTilde

Whether to support strikethrough with a single tilde (boolean, default: true). Single tildes work on github.com, but are technically prohibited by the GFM spec. Passed as singleTilde to micromark-extension-gfm-strikethrough.

options.tableCellPadding

Create tables with a space between cell delimiters (|) and content (boolean, default: true). Passed to mdast-util-gfm-table.

options.tablePipeAlign

Align the delimiters (|) between table cells so that they all align nicely and form a grid (boolean, default: true). Passed to mdast-util-gfm-table.

options.stringLength

Function passed to markdown-table to detect the length of a table cell (Function, default: s => s.length). Used to align table cells. Passed to mdast-util-gfm-table.

Security

Use of remark-gfm does not involve rehype (hast) or user content so there are no openings for cross-site scripting (XSS) attacks.

Related

• remark-github — Autolink references like in GitHub issues, PRs, and comments
• remark-footnotes — Footnotes
• remark-frontmatter — Frontmatter (YAML, TOML, and more)
• remark-math — Math

Contribute

See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer